# SQL Runner

The SQL Runner is a tool that allows you to execute SQL queries from Cube Cloud
on your data source or Cube Store. It can be used to inform the development of
the data model, for ad-hoc querying as well as debugging SQL queries generated
by Cube to execute against the data source.

<SuccessBox>

The SQL Runner is available in Cube Cloud on
[all product tiers](https://cube.dev/pricing).

</SuccessBox>

<video width="100%" controls>
  <source
    src="https://ucarecdn.com/8cbdd639-e86b-4190-bbaa-37122c39bc01/video.mp4"
    type="video/mp4"
  />
</video>

## Executing queries

To execute a query, enter the SQL query in the text area under **SQL Editor**
and click <Btn>▶ Run</Btn>. The query results will be displayed under
**Results**, along with the row count and query execution time:

<Screenshot
  highlight="inset(12% 2% 1% 41% round 10px)"
  src="https://ucarecdn.com/2f910abf-5b94-43cd-87f8-14c86bd98f77/"
/>

## Querying data sources

SQL Runner can run queries against configured data sources, which is
helpful for diagnosing database-specific issues.

<InfoBox>

In order for an additional data source to show up in SQL Runner, it needs to be
the [data source][ref-cube-datasource] in at least one cube definition.

</InfoBox>

It can also run queries against Cube Store, which is useful for testing
pre-aggregations directly to see if they return expected results.

You can switch data source(s) by clicking the dropdown under <Btn>Data Source</Btn>:

<Screenshot
  highlight="inset(25% 60% 53% 6% round 10px)"
  src="https://ucarecdn.com/5bd43e2c-c8e6-4300-a89b-036398e92175/"
/>

## Using a Security Context

The SQL Runner also allows executing queries against [configured data
sources][ref-conf-ref-driverfactory] using a specific security context, which is
particularly convenient for debugging [queries in a multi-tenant
configuration][ref-recipe-multi-src-same-model]. The SQL Runner can be
configured to use predefined security contexts from
[`scheduledRefreshContexts`][ref-conf-scheduled-refresh-ctx] in the `cube.js`
configuration file, or a custom context can be provided as a JSON string.

Specifying a security context is optional, and if none is provided, the query
will be executed with the default security context. If one is provided, then the
**Schema Explorer** will reload to reflect the data source available to the
security context.

[ref-conf-ref-driverfactory]: /product/configuration/reference/config#driverfactory
[ref-recipe-multi-src-same-model]:
  /product/configuration/recipes/multiple-sources-same-schema

### Scheduled Refresh Contexts

If you have configured
[`scheduledRefreshContexts`][ref-conf-scheduled-refresh-ctx] in your deployment,
you can choose a context to execute the query with. Click the dropdown under
**Security Context**, then use the <Btn>Scheduled Refresh Contexts</Btn> tab to
select an existing context:

<Screenshot src="https://ucarecdn.com/f3664be8-8214-4b27-88bb-f8cd85fc934f/" />

### Custom Contexts

The SQL Runner also allows providing an ad-hoc security context as a JSON
string. From the same dropdown under **Security Context**, click the <Btn>Custom
Context</Btn> tab and enter a valid JSON string and click <Btn>Apply</Btn>:

<Screenshot src="https://ucarecdn.com/955fa2c7-31c5-459e-adfb-498fbaf7bbb6/" />

## Viewing schema details

The Schema Explorer allows you to view details of the data source's schema,
including tables and their columns and types. This is useful for ensuring that
properties of data models match the underlying schema (i.e. a `number` property
in a data model should be a `numeric`).

<Screenshot
  highlight="inset(37% 60% 0% 6% round 10px)"
  src="https://ucarecdn.com/c2735f7c-d5e7-4b6b-903b-8d0db07b668e/"
/>


[ref-conf-scheduled-refresh-ctx]:
  /product/configuration/reference/config#scheduledrefreshcontexts
[ref-cube-datasource]: /product/data-modeling/reference/cube#data_source